﻿//-----------------------------------------------------------------------------------------
// <copyright file="FMRadio.cs" company="Jakub Florczyk (www.jakubflorczyk.pl)">
//      Copyright © 2009 Jakub Florczyk (www.jakubflorczyk.pl)
//      http://samsungmobilesdknet.codeplex.com
// </copyright>
//-----------------------------------------------------------------------------------------

namespace SamsungMobileSDKNET
{
    using System;
    using System.Runtime.InteropServices;

    /// <summary>
    /// Pointer to function that handles RDS Field events. The registered field type's current value is returned as paramters.
    /// </summary>
    /// <param name="type">FM Radio RDS Field type.</param>
    /// <param name="data">Pointer to data.</param>
    /// <param name="dataSize">Size of data.</param>
    public delegate void FMRadioRDSEventHandler(FMRadioRDSFieldType type, IntPtr data, uint dataSize);

    /// <summary>
    /// FM Radio Geographical Region.
    /// </summary>
    public enum FMRadioRegion
    {
        /// <summary>
        /// USA region.
        /// </summary>
        USA,

        /// <summary>
        /// Europe region.
        /// </summary>
        Europe,

        /// <summary>
        /// Japan region.
        /// </summary>
        Japan,

        /// <summary>
        /// Seasia region.
        /// </summary>
        SEAsia,

        /// <summary>
        /// China region.
        /// </summary>
        China
    }

    /// <summary>
    /// FM Radio RDS Fields.
    /// </summary>
    public enum FMRadioRDSFieldType
    {
        /// <summary>
        /// Station ID.
        /// </summary>
        StationID,

        /// <summary>
        /// Programme Service name.
        /// </summary>
        PSName,

        /// <summary>
        /// Alternative frequency.
        /// </summary>
        AltFreq,

        /// <summary>
        /// Program type.
        /// </summary>
        ProgType
    }

    /// <summary>
    /// FM Radio Seek Directions 
    /// </summary>
    public enum FMRadioSeekDirection
    {
        /// <summary>
        /// Seek upward.
        /// </summary>
        Upward,

        /// <summary>
        /// Seek downward.
        /// </summary>
        Downward
    }

    /// <summary>
    /// Samsung FM Radio API.
    /// </summary>
    /// <remarks>
    /// The FM Radio API controls the phone's FM radio hardware. 
    /// <br/><br/>
    /// The specific features of the FM Radio vary from device to device.
    /// <br/>
    /// These are not specified by the Samsung FM Radio API. Please refer to device-specific documentation for these details.
    /// </remarks>
    public class FMRadio
    {
        /// <summary>
        /// Turn On the FM Radio.
        /// </summary>
        /// <param name="region">The FM broadcast geographical region.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is invalid 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioTurnOn")]
        public static extern ResultCode TurnOn(
            [In] FMRadioRegion region);

        /// <summary>
        /// Turn Off the FM Radio.
        /// </summary>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioTurnOff")]
        public static extern ResultCode TurnOff();
        
        /// <summary>
        /// Sets the device's FM Radio frequency.
        /// </summary>
        /// <param name="frequency">FM Radio frequency.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is invalid
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioSetFrequency")]
        public static extern ResultCode SetFrequency(
            [In] uint frequency);

        /// <summary>
        /// Gets the device's current FM Radio frequency.
        /// </summary>
        /// <param name="frequency">FM Radio current frequency.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioGetFrequency")]
        public static extern ResultCode GetFrequency(
            [Out] out uint frequency);

        /// <summary>
        /// Manually seek upwards or downwards to the FM Radio's next frequency.
        /// </summary>
        /// <param name="direction">Specifies upward or downward.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is invalid
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioManualSeek")]
        public static extern ResultCode ManualSeek(
            [In] FMRadioSeekDirection direction);

        /// <summary>
        /// Auto-seek upwards or downwards to the FM Radio's next valid frequency.
        /// </summary>
        /// <param name="direction">Specifies upward or downward.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is invalid
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioAutoSeek")]
        public static extern ResultCode AutoSeek(
            [In] FMRadioSeekDirection direction);

        /// <summary>
        /// Scans through all valid frequencies and returns a list of frequencies with a strong broadcast signal.
        /// </summary>
        /// <param name="presetFreq">Array of frequencies.</param>
        /// <param name="presetCount">Maximum number of presets to return.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is invalid
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioScan")]
        public static extern ResultCode Scan(
            [Out] out uint presetFreq,
            [In] uint presetCount);

        /// <summary>
        /// Cancel a frequency scan.
        /// </summary>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioCancelScan")]
        public static extern ResultCode CancelScan();

        /// <summary>
        /// Sets the device's FM Radio volume, in percentage (0-100).
        /// </summary>
        /// <param name="volume">FM Radio volume in percentage.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the value of the input parameter is not within 0 to 100
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioSetVolume")]
        public static extern ResultCode SetVolume(
            [In] uint volume);

        /// <summary>
        /// Gets the device's current FM Radio volume, in percentage.
        /// </summary>
        /// <param name="volume">FM Radio current volume, in percentage (0-100).</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioGetVolume")]
        public static extern ResultCode GetVolume(
            [Out] out uint volume);

        /// <summary>
        /// Gets the device's current FM Radio RSSI signal strength.
        /// </summary>
        /// <param name="sigStrength">FM Radio current RSSI signal strength (0-255), 255 being the strongest.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioGetRSSI")]
        public static extern ResultCode GetRSSI(
            [Out] out uint sigStrength);

        /// <summary>
        /// Gets the device's current FM Radio RDS Field.
        /// </summary>
        /// <param name="type">FM Radio RDS Field type.</param>
        /// <param name="data">A pointer to the RDS data. This will be set to NULL if the value was deleted.</param>
        /// <param name="dataSize">The number of bytes pointed to by pData. This value will be set to 0 if pData is NULL.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioGetRDSField")]
        public static extern ResultCode GetRDSField(
            [In] FMRadioRDSFieldType type,
            [In] IntPtr data, 
            [Out] out uint dataSize);

        /// <summary>
        /// Registers a callback handler to be called whenever the value of the specified field type changes. A client can only register one handler per process.
        /// </summary>
        /// <param name="type">FM Radio RDS Field type. </param>
        /// <param name="handler">Pointer to function that will handle the event.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if any input parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioRDSFieldRegisterOnChangeHandler")]
        public static extern ResultCode RDSFieldRegisterOnChangeHandler(
            [In] FMRadioRDSFieldType type,
            [In] FMRadioRDSEventHandler handler);

        /// <summary>
        /// Unregisters the handler registered by a previous call to the <see cref="M:SamsungMobileSDKNET.FMRadio.RDSFieldRegisterOnChangeHandler"/> function.
        /// </summary>
        /// <param name="type">FM Radio RDS Field type.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioRDSFieldUnregisterOnChangeHandler")]
        public static extern ResultCode RDSFieldUnregisterOnChangeHandler(
            [In] FMRadioRDSFieldType type);

        /// <summary>
        /// Unregisters all the handlers registered by a previous call to the <see cref="M:SamsungMobileSDKNET.FMRadio.RDSFieldRegisterOnChangeHandler"/> function.
        /// </summary>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiFMRadioRDSFieldUnregisterAllOnChangeHandlers")]
        public static extern ResultCode RDSFieldUnregisterAllOnChangeHandlers();
    }
}
